Upload data api three layer refactor by osama-rizk · Pull Request #14798 · aws-amplify/amplify-js

osama-rizk · 2026-04-30T14:38:26Z

Description of changes

Refactor the internal uploadData API in @aws-amplify/storage to follow the
three-layer architecture (foundation / client / server):

foundation/ — environment-agnostic core. Contains calculateContentCRC32
and calculateContentMd5, which now receive a FoundationContext
({ amplify, readFile, toBase64 }) via dependency injection instead of
branching on the runtime.
client/ — browser + React Native implementations of readFile and
toBase64 (with .native.ts splits preserved), plus the public
client-side uploadData API.
server/ — Node.js implementations and the public server-side
uploadData API, which injects the request-scoped Amplify instance from
getAmplifyServerContext.

The uploadData call graph (putObjectJob, getMultipartUploadHandlers,
uploadPartExecutor, loadOrCreateMultipartUpload) now threads
FoundationContext instead of AmplifyClassV6, so the foundation layer is
fully free of environment-discriminating logic.

Public API surface is unchanged. Routing to the correct bundle per
environment is handled via conditional exports in package.json
(browser / import / require), and the existing
aws-amplify/storage/server subpath is preserved for backward compatibility.

Legacy providers/s3/utils/{crc32,md5,readFile}.ts are kept as shims for
deleteObjects until remove is migrated; new code imports from
foundation/utils and client|server/utils instead.

This is the first API migrated to the three-layer pattern; follow-up PRs
will apply the same split to the remaining Storage APIs.

Issue #, if available

N/A — internal refactor, no customer-facing behavior change.

Description of how you validated changes

Existing unit tests for uploadData updated to pass FoundationContext
instead of Amplify; all continue to pass.
Added direct unit tests for the new foundation/utils/*,
client/utils/*, and server/utils/* modules. New code has 100%
statement/function/line coverage.
aws-amplify Jest config now runs two projects so the umbrella
package's exports are verified under both resolution paths:
- node project (pinned customExportConditions: ['node']) — existing
  tests, asserts the SSR surface of @aws-amplify/storage in
  exports.test.ts.
- browser project (jsdom defaults) — new exports.browser.test.ts
  asserts the full client-side surface (uploadData, downloadData,
  remove, list, getProperties, copy, getUrl, isCancelError,
  StorageError, DEFAULT_PART_SIZE).
- babel-jest with @babel/preset-env (modules: 'commonjs') is used
  to transform the .mjs ESM bundle emitted by @aws-amplify/storage
  so Jest can load it under the browser condition; ts-jest continues to
  handle .ts/.js.
predictions Jest config no longer pins the node export condition.
It provides a global moduleNameMapper stub for @aws-amplify/storage
(predictions only consumes getUrl), which removes the need for a
resolution pin. Existing per-test jest.mock(...) overrides still work.
yarn test passes for the storage, aws-amplify, and predictions
packages. Package-level coverage thresholds respected.

Checklist

PR description included
yarn test passes
Unit Tests are changed or added
Relevant documentation is changed or added (and PR referenced)

Checklist for repo maintainers

Verify E2E tests for existing workflows are working as expected or add E2E tests for newly added workflows
New source file paths included in this PR have been added to CODEOWNERS, if appropriate

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

changeset-bot · 2026-04-30T14:38:31Z

🦋 Changeset detected

Latest commit: 2e18fed

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@aws-amplify/storage	Minor
aws-amplify	Minor
@aws-amplify/predictions	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

…-layer-refactor

* fix: update change set config. * add change set back

soberm · 2026-05-08T11:23:46Z

+		return Buffer.from(input, 'utf-8').toString('base64');
+	}
+
+	return Buffer.from(input.buffer).toString('base64');


Both the React Native and server toBase64 implementations ignore byteOffset and byteLength. The browser implementation correctly uses new Uint8Array(input.buffer, input.byteOffset, input.byteLength)

Updated both implementation (server & RN ) ✅

bobbor

looking at the 3 files (client/utils/toBase64.ts, client/utils/toBase64.native.ts and server/utils/toBase64.ts) they all do the same and can result in a foundation/utils/toBase64.ts.

the client file uses low-level constructs (Uint8Array, TextEncoder and btoa) which are available in all environments.

so I'd suggest:

take the client/util/toBase64.ts move that to foundation/util/toBase64.ts + test
remove the native and server implementations + tests
remove the toBase64 from the FoundationContext

Replace the per-environment client/server toBase64 implementations with a single foundation/utils/toBase64.ts. The browser-style impl using TextEncoder/btoa/Uint8Array works in all supported runtimes (Node 18+, modern browsers, React Native), so toBase64 no longer needs DI through FoundationContext.

osama-rizk · 2026-05-11T10:42:50Z

looking at the 3 files (client/utils/toBase64.ts, client/utils/toBase64.native.ts and server/utils/toBase64.ts) they all do the same and can result in a foundation/utils/toBase64.ts.

the client file uses low-level constructs (Uint8Array, TextEncoder and btoa) which are available in all environments.

so I'd suggest:

take the client/util/toBase64.ts move that to foundation/util/toBase64.ts + test

remove the native and server implementations + tests

remove the toBase64 from the FoundationContext

Done ✅ toBase64 is consolidated and are part of the foundation layer.

osama-rizk and others added 6 commits April 29, 2026 11:46

feat(storage): add server uploadData api

7ef4156

add a changeset

ef355fb

update upload data api types

9d87514

docs(storage): fix @throws JSDoc syntax in uploadData APIs

67ebab2

Merge branch 'main' into feat/storage/upload-data-api

fa98843

Merge branch 'main' into feat/storage/upload-data-api

12af5cf

osama-rizk changed the base branch from feat/storage/upload-data-api to main April 30, 2026 15:58

osama-rizk changed the base branch from main to feat/storage/upload-data-api April 30, 2026 16:02

osama-rizk added 6 commits April 30, 2026 18:04

Add client layer

a71bed7

export server API

2822a8d

refactor(storage): inject readFile via FoundationContext

3ffa268

refactor(storage): inject toBase64 via FoundationContext

0aa15c3

test(storage): update uploadData tests for FoundationContext

090abf4

add a changeset

97d6321

osama-rizk force-pushed the upload-data-api-three-layer-refactor branch from 9726d21 to 97d6321 Compare April 30, 2026 16:05

Base automatically changed from feat/storage/upload-data-api to main May 4, 2026 08:20

osama-rizk and others added 7 commits May 4, 2026 11:08

Merge remote-tracking branch 'origin/main' into upload-data-api-three…

5d229be

…-layer-refactor

add conditional exports

74ea9d8

fix(storage): jest configs pin to node condition after browser export

c256488

fix: update change set config. (#14800)

9df46ec

* fix: update change set config. * add change set back

Merge branch 'main' into upload-data-api-three-layer-refactor

19ebe2e

test(storage): add unit tests for foundation, client and server utils

aa47ed6

test: split aws-amplify exports into node and browser jest projects

337c101

osama-rizk added the run-tests run the pr-label workflow label May 5, 2026

osama-rizk marked this pull request as ready for review May 5, 2026 12:01

osama-rizk requested review from a team, avi-karthik, pranavosu and sarayev as code owners May 5, 2026 12:01

osama-rizk and others added 3 commits May 5, 2026 15:15

Merge branch 'main' into upload-data-api-three-layer-refactor

d53aad9

revert(storage): restore pre-refactor exports["."] and jest configs

b46de7c

Merge branch 'main' into upload-data-api-three-layer-refactor

46eacc1

bobbor previously approved these changes May 8, 2026

View reviewed changes

soberm reviewed May 8, 2026

View reviewed changes

fix(storage): honor byteOffset/byteLength in native and server toBase64

ac2ea76

osama-rizk dismissed bobbor’s stale review via ac2ea76 May 8, 2026 14:23

Merge branch 'main' into upload-data-api-three-layer-refactor

c8700ed

soberm previously approved these changes May 8, 2026

View reviewed changes

bobbor requested changes May 11, 2026

View reviewed changes

osama-rizk dismissed soberm’s stale review via 2e18fed May 11, 2026 10:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Upload data api three layer refactor#14798

Upload data api three layer refactor#14798
osama-rizk wants to merge 25 commits intomainfrom
upload-data-api-three-layer-refactor

osama-rizk commented Apr 30, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Apr 30, 2026 •

edited

Loading

Uh oh!

soberm May 8, 2026

Uh oh!

osama-rizk May 8, 2026 •

edited

Loading

Uh oh!

bobbor left a comment

Uh oh!

osama-rizk commented May 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

osama-rizk commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of changes

Issue #, if available

Description of how you validated changes

Checklist

Checklist for repo maintainers

Uh oh!

changeset-bot Bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

soberm May 8, 2026

Choose a reason for hiding this comment

Uh oh!

osama-rizk May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bobbor left a comment

Choose a reason for hiding this comment

Uh oh!

osama-rizk commented May 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

osama-rizk commented Apr 30, 2026 •

edited

Loading

changeset-bot Bot commented Apr 30, 2026 •

edited

Loading

osama-rizk May 8, 2026 •

edited

Loading